/**
 * Copyright (c) 2009 Cerner Corporation.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Cerner Corporation - initial API and implementation
 */
package com.cerner.system.rest.internal.arguments;

import java.util.List;

/**
 * Internal SPI that allows a component to publish a validation algorithm for
 * method and constructor arguments.
 * 
 * @author Alex Horn
 * @see Verifier#Verifier(Validator, Validator...)
 */
public interface Validator {

  /**
   * Determine if the argument should be validated. If this method returns
   * {@code true}, then {@link #isValid(Object)} will be invoked.
   * 
   * @param argument argument object that may be eligible for validation
   * @return boolean {@code true} if the argument should be validated or {@code
   *         false} if no further checks should be performed
   */
  boolean canValidate(Object argument);

  /**
   * Check the argument against a set of conditions that have to be met.
   * 
   * @param argument argument object to be validated
   * @return boolean {@code true} if the argument is valid or {@code false} if it
   *         does not comply with the rules
   */
  boolean isValid(Object argument);

  /**
   * Construct a human-readable error message that explains why the validator
   * rejected the provided argument.
   * 
   * @param names list of names that correspond to argument objects that have
   *          been found to be invalid
   * @return human-readable error message
   */
  String message(List<String> names);

}
